'\" t
.\"     Title: IPSEC.SECRETS
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 10/06/2010
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "IPSEC\&.SECRETS" "5" "10/06/2010" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec.secrets \- secrets for IKE/IPsec authentication
.SH "DESCRIPTION"
.PP
The file
ipsec\&.secrets
contains a list of secrets, aka preshared secrets, RSA signatures, or pointers to X\&.509 Digital Certificates\&. These secrets are used by
\fBipsec_pluto\fR(8)
, the Openswan Internet Key Exchange daemon, to authenticate other hosts\&. Currently there are five kinds of secrets: preshared secrets, RSA private keys, passphrases for X\&.509 certificates and if compiled with
\fBUSE_XAUTH=true\fR
there is support for XAUTH static passwords\&. Smartcard support has been moved to the NSS framework\&.
.PP
It is vital that these secrets be protected\&. The file should be owned by root, and permissions should be set to block all access by others\&. (eg: chmod 600)
.PP
The file is a sequence of entries and include directives\&. Here is an example \- each entry or directive must start at the left margin, but if it continues beyond a single line, each continuation line must be indented\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# sample /etc/ipsec\&.secrets file for 10\&.1\&.0\&.1
10\&.1\&.0\&.1 10\&.2\&.0\&.1: PSK "secret shared by two hosts"
# sample roadwarrior
%any gateway\&.corp\&.com: PSK "shared secret with many roadwarriors"
# sample server for roadwarriors
myip %any : PSK "shared secret with many roadwarriors"

# an entry may be split across lines,
# but indentation matters
www\&.xs4all\&.nl @www\&.kremvax\&.ru
\ \&\ \&\ \&\ \&10\&.6\&.0\&.1 10\&.7\&.0\&.1 1\&.8\&.0\&.1: PSK "secret shared by 5 systems"

# an RSA private key\&.
# note that the lines are too wide for a
# man page, so \&.\&.\&. has been substituted for
# the truncated part
@my\&.com: rsa {
\ \&\ \&\ \&\ \&Modulus:\ \&0syXpo/6waam+ZhSs8Lt6jnBzu3C4grtt\&.\&.\&.
\ \&\ \&\ \&\ \&PublicExponent:\ \&0sAw==
\ \&\ \&\ \&\ \&PrivateExponent:\ \&0shlGbVR1m8Z+7rhzSyenCaBN\&.\&.\&.
\ \&\ \&\ \&\ \&Prime1:\ \&0s8njV7WTxzVzRz7AP+0OraDxmEAt1BL5l\&.\&.\&.
\ \&\ \&\ \&\ \&Prime2:\ \&0s1LgR7/oUMo9BvfU8yRFNos1s211KX5K0\&.\&.\&.
\ \&\ \&\ \&\ \&Exponent1:\ \&0soaXj85ihM5M2inVf/NfHmtLutVz4r\&.\&.\&.
\ \&\ \&\ \&\ \&Exponent2:\ \&0sjdAL9VFizF+BKU4ohguJFzOd55OG6\&.\&.\&.
\ \&\ \&\ \&\ \&Coefficient:\ \&0sK1LWwgnNrNFGZsS/2GuMBg9nYVZ\&.\&.\&.
\ \&\ \&\ \&\ \&}

# An X\&.509 pem encoded private key file with (optional) passphrase
: RSA vpnserverKey\&.pem "<optional passphrase>"
# An X\&.509 pem encoded private key file locked with a passphrase
# Note: the %prompt keyword means someone has to actually enter the passphrase
# at load time \- usually via \fBipsec_whack\fR(8)
:  RSA vpnserverKey\&.pem %prompt

# XAUTH password, used with leftxauthusername=username
@username : XAUTH "password"

include ipsec\&.*\&.secrets	# get secrets from other files
.fi
.if n \{\
.RE
.\}
.sp

Each entry in the file is a list of indices, followed by a secret\&. The two parts are separated by a colon (\fB:\fR) that is followed by whitespace or a newline\&. For compatibility with the previous form of this file, if the key part is just a double\-quoted string the colon may be left out\&. If filenames are not absolute paths, they are relative to the
\fBipsec\&.d/private/\fR
directory\&.
.PP
An index is an IP address, or a Fully Qualified Domain Name, user@FQDN,
\fB%any\fR
or
\fB%any6\fR
(other kinds may come)\&. An IP address may be written in the familiar dotted quad form or as a domain name to be looked up when the file is loaded (or in any of the forms supported by the Openswan
\fBipsec_ttoaddr\fR(3)
routine)\&. In many cases it is a bad idea to use domain names because the name server may not be running or may be insecure\&. To denote a Fully Qualified Domain Name (as opposed to an IP address denoted by its domain name), precede the name with an at sign (\fB@\fR)\&.
.PP
Matching IDs with indices is fairly straightforward: they have to be equal\&. In the case of a \(lqRoad Warrior\(rq connection, if an equal match is not found for the Peer\'s ID, and it is in the form of an IP address, an index of
\fB%any\fR
will match the peer\'s IP address if IPV4 and
\fB%any6\fR
will match a the peer\'s IP address if IPV6\&. Currently, the obsolete notation
0\&.0\&.0\&.0
may be used in place of
\fB%any\fR, but please stop doing this, as it will likely stop working around Openswan v3\&.0\&.
.PP
This file is only read at startup time\&. If any changes are made to this file, the pluto daemon should be told to re\-read this file using the command
\fBipsec secrets\fR
or
\fBipsec auto \-\-rereadsecrets\fR\&. If there are any keyfiles protected by a passphrase using
\fB%prompt\fR, you will be prompted again to enter these passphrases\&. To skip the prompting, just hit return to skip unlocking that particular private key\&. Note that currently there is no way to add a specific new entry \- it\'s all or nothing\&.
.PP
Smartcard support has been moved from Openswan to NSS\&. Please see the NSS documentation on how to configure smartcards\&.
.PP
An additional complexity arises in the case of authentication by preshared secret: the responder will need to look up the secret before the Peer\'s ID payload has been decoded, so the ID used will be the IP address\&.
.PP
To authenticate a connection between two hosts, the entry that most specifically matches the host and peer IDs is used\&. An entry with no index will match any host and peer\&. More specifically, an entry with one index will match a host and peer if the index matches the host\'s ID (the peer isn\'t considered)\&. Still more specifically, an entry with multiple indices will match a host and peer if the host ID and peer ID each match one of the indices\&. If the key is for an asymmetric authentication technique (i\&.e\&. a public key system such as RSA), an entry with multiple indices will match a host and peer even if only the host ID matches an index (it is presumed that the multiple indices are all identities of the host)\&. It is acceptable for two entries to be the best match as long as they agree about the secret or private key\&.
.PP
Authentication by preshared secret requires that both systems find the identical secret (the secret is not actually transmitted by the IKE protocol)\&. If both the host and peer appear in the index list, the same entry will be suitable for both systems so verbatim copying between systems can be used\&. This naturally extends to larger groups sharing the same secret\&. Thus multiple\-index entries are best for PSK authentication\&.
.PP
Authentication by RSA Signatures requires that each host have its own private key\&. A host could reasonably use a different private keys for different interfaces and for different peers\&. But it would not be normal to share entries between systems\&. Thus no\-index and one\-index forms of entry often make sense for RSA Signature authentication\&.
.PP
The key part of an entry may start with a token indicating the kind of key\&. \(lqRSA\(rq signifies RSA private key and \(lqPSK\(rq signifies PreShared Key (case is ignored)\&. For compatibility with previous forms of this file, PSK is the default\&.
.PP
The token \(lqXAUTH\(rq indicates a eXtended Authentication password\&. There should be one indice, and it should be in the @FQDN format\&. The file will be searched with the XAUTH username, which is usually provided in the configuration file\&. XAUTH is otherwise identical to PSK in syntax\&.
.PP
If the RSA points to a filename, this is assumed to be a PEM (or DER?) encoded X\&.509 private key\&. The private key may be protected by a 3DES encryption\&. 1DES encrypted key files will be rejected\&. If the private key is protected by a passphrase and this passphrase is not specified in
\fBipsec\&.secrets\fR, the connection cannot be automatically started using
\fBauto=start\fR, but instead must be brought up using
\fBipsec auto \-\-up connname\fR, upon which the user will be prompted for the passphrase to unlock the private key belonging to the X\&.509 certificate\&. PKCS#12 files, which include the private key file, cannot be specified in
\fBipsec\&.secrets\fR\&. Private keys can be extracted from PKCS#12 files using the following command:
\fBopenssl pkcs12 \-nocerts \-in clientCert\&.p12 \-out clientKey\&.pem\fR
.PP
A preshared secret is most conveniently represented as a sequence of characters, delimited by the double\-quote character (\fB"\fR)\&. The sequence cannot contain a newline or double\-quote\&. Strictly speaking, the secret is actually the sequence of bytes that is used in the file to represent the sequence of characters (excluding the delimiters)\&. A preshared secret may also be represented, without quotes, in any form supported by
\fBipsec_ttodata\fR(3)\&.
.PP
An RSA private key is a composite of eight generally large numbers\&. The notation used is a brace\-enclosed list of field name and value pairs (see the example above)\&. A suitable key, in a suitable format, may be generated by
\fBipsec_rsasigkey\fR(8)\&. The structure is very similar to that used by BIND 8\&.2\&.2 or later, but note that the numbers must have a \(lq0s\(rq prefix if they are in base 64\&. The order of the fields is fixed\&.
.PP
The first token an entry must start in the first column of its line\&. Subsequent tokens must be separated by whitespace, except for a colon token, which only needs to be followed by whitespace\&. A newline is taken as whitespace, but every line of an entry after the first must be indented\&.
.PP
Whitespace at the end of a line is ignored (except in the 0t notation for a key)\&. At the start of line or after whitespace,
\fB#\fR
and the following text up to the end of the line is treated as a comment\&. Within entries, all lines must be indented (except for lines with no tokens)\&. Outside entries, no line may be indented (this is to make sure that the file layout reflects its structure)\&.
.PP
An include directive causes the contents of the named file to be processed before continuing with the current file\&. The filename is subject to \(lqglobbing\(rq as in
\fBsh\fR(1), so every file with a matching name is processed\&. Includes may be nested to a modest depth (10, currently)\&. If the filename doesn\'t start with a
\fB/\fR, the directory containing the current file is prepended to the name\&. The include directive is a line that starts with the word
\fBinclude\fR, followed by whitespace, followed by the filename (which must not contain whitespace)\&.
.SH "FILES"
.PP
/etc/ipsec\&.secrets
.SH "SEE ALSO"
.PP
The rest of the Openswan distribution, in particular
\fBipsec.conf\fR(5),
\fBipsec\fR(8),
\fBipsec_newhostkey\fR(8),
\fBipsec_rsasigkey\fR(8),
\fBipsec_showhostkey\fR(8),
\fBipsec_auto\fR(8)
\fB\-\-rereadsecrets\fR, and
\fBipsec_pluto\fR(8)
\fB\-\-listen\fR,\&.
BIND 8\&.2\&.2 or later,
\m[blue]\fBftp://ftp\&.isc\&.org/isc/bind/src/\fR\m[]
.SH "HISTORY"
.PP
Originally designed for the FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by D\&. Hugh Redelmeier\&. Updated for Openswan by Ken Bantoft\&.
.SH "BUGS"
.PP
If an ID is
0\&.0\&.0\&.0, it will match
\fB%any\fR; if it is
\fB0::0\fR, it will match
\fB%any6\fR\&.
